docs: Make the contribution guide slightly more friendly

This is an important document for newcomers, so we should err on the
side of being more detailed on what kind of contributions we expect,
and how we expect them.

The text is heavily modelled on the contributing-template by Nadia
Eghbal available here:

  https://github.com/nayafia/contributing-template

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 837a61be83efa58a734c51f32571d39513744b75..b1aef7a3dc2fe01d13dd3588571cb8a7a560cf72 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,27 +1,123 @@
-If you want to hack on the GTK+ project, you'll need to have the development
-tools appropriate for your operating system, including:
+# Contribution guidelines
+
+Thank you for considering contributing to the GTK project!
+
+These guidelines are meant for new contributors, regardless of their level
+of proficiency; following them allows the maintainers of the GTK project to
+more effectively evaluate your contribution, and provide prompt feedback to
+you. Additionally, by following these guidelines you clearly communicate
+that you respect the time and effort that the people developing GTK put into
+managing the project.
+
+GTK is a complex free software GUI toolkit, and it would not exist without
+contributions from the free and open source software community. There are
+many things that we value:
+
+ - bug reporting and fixing
+ - documentation and examples
+ - tests
+ - new features
+
+Please, do not use the issue tracker for support questions. If you have
+questions on how to use GTK effectively, you can use:
+
+ - the `#gtk+` IRC channel on irc.gnome.org
+ - the [gtk](https://mail.gnome.org/mailman/listinfo/gtk-list) mailing list,
+   for general questions on GTK
+ - the [gtk-app-devel](https://mail.gnome.org/mailman/listinfo/gtk-app-devel-list)
+   mailing list, for questions on application development with GTK
+ - the [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list)
+   mailing list, for questions on developing GTK itself
+
+You can also look at the GTK tag on [Stack
+Overflow](https://stackoverflow.com/questions/tagged/gtk).
+
+The issue tracker is meant to be used for actionable issues only.
+
+## How to report bugs
+
+### Security issues
+
+You should not open a new issue for security related questions.
+
+When in doubt, send an email to the [security](mailto:security@gnome.org)
+mailing list.
+
+### Bug reports
+
+If you're reporting a bug make sure to list:
+
+ 0. which version of GTK are you using?
+ 0. which operating system are you using?
+ 0. the necessary steps to reproduce the issue
+ 0. the expected outcome
+ 0. a description of the behavior; screenshots are also welcome
+ 0. a small, self-contained example exhibiting the behavior; if this
+    is not available, try reproducing the issue using the GTK examples
+    or interactive tests
+
+If the issue includes a crash, you should also include:
+
+ 0. the eventual warnings printed on the terminal
+ 0. a backtrace, obtained with tools such as GDB or LLDB
+
+For small issues, such as:
+
+ - spelling/grammar fixes in the documentation
+ - typo correction
+ - comment clean ups
+ - changes to metadata files (CI, `.gitignore`)
+ - build system changes
+ - source tree clean ups and reorganizations
+
+You should directly open a merge request instead of filing a new issue.
+
+### Features and enhancements
+
+Feature discussion can be open ended and require high bandwidth channels; if
+you are proposing a new feature on the issue tracker, make sure to make
+an actionable proposal, and list:
+
+ 0. what you're trying to achieve
+ 0. prior art, in other toolkits or applications
+ 0. design and theming changes
+
+If you're proposing the integration of new features it helps to have
+multiple applications using shared or similar code, especially if they have
+iterated over it various times.
+
+Each feature should also come fully documented, and with tests.
+
+## Your first contribution
+
+### Prerequisites
+
+If you want to contribute to the GTK project, you will need to have the
+development tools appropriate for your operating system, including:
 
  - Python 3.x
  - Meson
  - Ninja
  - Gettext (19.7 or newer)
- - a C99 compatible compiler
+ - a [C99 compatible compiler](https://wiki.gnome.org/Projects/GLib/CompilerRequirements)
 
 Up-to-date instructions about developing GNOME applications and libraries
-can be found here:
-
- * https://developer.gnome.org
+can be found on [the GNOME Developer Center](https://developer.gnome.org).
 
-Information about using GitLab with GNOME can be found here:
+The GTK project uses GitLab for code hosting and for tracking issues. More
+information about using GitLab can be found [on the GNOME
+wiki](https://wiki.gnome.org/GitLab).
 
- * https://wiki.gnome.org/GitLab
+### Dependencies
 
-In order to get Git GTK+ installed on your system, you need to have the
-required versions of all the GTK+ dependencies; typically, this means a
+In order to get GTK from Git installed on your system, you need to have the
+required versions of all the GTK dependencies; typically, this means a
 recent version of GLib, Cairo, Pango, and ATK, as well as the platform
 specific dependencies for the windowing system you are using (Wayland, X11,
 Windows, or macOS).
 
+### Getting started
+
 You should start by forking the GTK repository from the GitLab web UI, and
 cloning from your fork:
 
@@ -38,7 +134,7 @@ $ git clone git@gitlab.gnome.org:GNOME/gtk.git
 $ cd gtk
 ```
 
-To compile the Git version of GTK+ on your system, you will need to
+To compile the Git version of GTK on your system, you will need to
 configure your build using Meson:
 
 ```sh
@@ -55,9 +151,15 @@ $ git checkout -b your-branch
 
 Once you've finished working on the bug fix or feature, push the branch
 to the Git repository and open a new merge request, to let the GTK
-maintainers review your contribution. The [CODE-OWNERS](./docs/CODE-OWNERS)
-document contains the list of core contributors to GTK and the areas for
-which they are responsible.
+maintainers review your contribution.
+
+### Code reviews
+
+Each contribution is reviewed by the core developers of the GTK project.
+
+The [CODE-OWNERS](./docs/CODE-OWNERS) document contains the list of core
+contributors to GTK and the areas for which they are responsible; you
+should ensure to receive their review and signoff on your changes.
 
 ### Commit messages
 
@@ -70,6 +172,8 @@ Longer explanation explaining exactly what's changed, whether any
 external or private interfaces changed, what bugs were fixed (with bug
 tracker reference if applicable) and so forth. Be concise but not too
 brief.
+
+Closes #1234
 ```
 
  - Always add a brief description of the commit to the _first_ line of
@@ -106,38 +210,42 @@ Fixes #1234
   or:
 
 ```plain
-Closes https://gitlab.gnome.org/GNOME/gtk/issues/1234
+Closes: https://gitlab.gnome.org/GNOME/gtk/issues/1234
 ```
 
 ### Access to the GTK repository
 
-GTK+ is part of the GNOME infrastructure. At the current time, any
-person with write access to the GNOME repository can make changes to
-GTK+. This is a good thing, in that it encourages many people to work
-on GTK+, and progress can be made quickly. However, GTK+ is a fairly
-large and complicated package that many other things depend on, so to
+GTK is part of the GNOME infrastructure. At the current time, any
+person with write access to the GNOME repository can merge changes to
+GTK. This is a good thing, in that it encourages many people to work
+on GTK, and progress can be made quickly. However, GTK is a fairly
+large and complicated project on which many other things depend, so to
 avoid unnecessary breakage, and to take advantage of the knowledge
-about GTK+ that has been built up over the years, we'd like to ask
-people committing to GTK+ to follow a few rules:
+about GTK that has been built up over the years, we'd like to ask
+people committing to GTK to follow a few rules:
 
 0. Ask first. If your changes are major, or could possibly break existing
-   code, you should always ask. If your change is minor and you've
-   been working on GTK+ for a while it probably isn't necessary
-   to ask. But when in doubt, ask. Even if your change is correct,
-   somebody may know a better way to do things.
-   If you are making changes to GTK+, you should be subscribed
-   to [gtk-devel-list](https://mail.gnome.org/mailman/listinfo/gtk-devel-list).
-   This is a good place to ask about intended changes.
-   `#gtk+` on GIMPNet (irc.gnome.org) is also a good place to find GTK+
+   code, you should always ask. If your change is minor and you've been
+   working on GTK for a while it probably isn't necessary to ask. But when
+   in doubt, ask. Even if your change is correct, somebody may know a
+   better way to do things. If you are making changes to GTK, you should
+   be subscribed to the [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list)
+   mailing list; this is a good place to ask about intended changes.
+   The `#gtk+` IRC channel on irc.gnome.org is also a good place to find GTK
    developers to discuss changes, but if you live outside of the EU/US time
-   zones, email to gtk-devel-list is the most certain and preferred method.
+   zones, an email to the gtk-devel mailing list is the most certain and
+   preferred method.
 
 0. Ask _first_.
 
 0. Always write a meaningful commit message. Changes without a sufficient
    commit message will be reverted.
 
-0. Never push to master directly; you should always go through a merge
-   request, to ensure that the code is tested on the CI infrastructure
+0. Never push to a public branch directly; you should always go through
+   a merge request, to ensure that the code is tested on the CI infrastructure
    at the very least. A merge request is also the proper place to get a
    comprehensive code review from the core developers of GTK.
+
+If you have been contributing to GTK for a while and you don't have commit
+access to the repository, you may ask to obtain it following the [GNOME account
+process](https://wiki.gnome.org/AccountsTeam/NewAccounts).